Bank Account - BRL

Introduction

The Bank Account - BRL establishes a connection between the traditional Brazilian Real (BRL) payment system and blockchain systems, acting as a bridge for seamless transactions.

This section will guide you through providing visibility of the Bank Account - BRL within Avenia API for efficient and secure integrations.

Bank Account - BRL Initialization

The initialization of your Bank Account - BRL is performed during the creation of your Business Account (BA). Upon creating your Business Account, a fiat rail is automatically initialized along with Avenia wallets by default. You will have visibility of these details in the following sections.

Get Bank Account - BRL Information

Since Bank Account - BRL was initialized during the creation of your business account, we will now retrieve this information.

HTTP GET Request

https://api.sandbox.avenia.io:10952/v2/account/bank-accounts/brl/

cURL Example:

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/bank-accounts/brl/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "status": "ACTIVE",
  "bankName": "Example Bank",
  "pixKey": "11111111-1111-1111-1111-111111111111",
  "ispb": "00000000",
  "bankCode": "000",
  "branchCode": "0000",
  "accountNumber": "0000000000000000",
  "accountType": "payment",
  "createdAt": "2025-03-10T15:23:17.801357Z"
}

note

This endpoint returns the main-account-level BRL rail. To retrieve the deposit PIX key and BR Code of a specific account or sub-account, use GET /v2/account/account-info, which accepts a subAccountId and returns the pixKey and a per-account/sub-account brCode. When you need to tell apart deposits from different sub-accounts, use the sub-account's brCode — the pixKey is shared across the Business Account.

Get a Sub-Account's Deposit PIX Key & BR Code

Each sub-account can receive BRL deposits. To fetch a sub-account's deposit pixKey and its unique brCode, call the Account Info endpoint with the sub-account's subAccountId.

Parameters

Field	Type	Description
`subAccountId`	string	The sub-account to fetch. Omit it to retrieve the main account's deposit information instead.

HTTP GET Request

https://api.sandbox.avenia.io:10952/v2/account/account-info?subAccountId=<SUB_ACCOUNT_ID>

cURL Example:

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/account-info?subAccountId=00000000-0000-0000-0000-000000000000" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "id": "00000000-0000-0000-0000-000000000000",
  "wallets": [
    {
      "id": "be85cef0-d70a-47cc-9847-9014570efed5",
      "walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "chain": "EVM"
    }
  ],
  "pixKey": "11111111-1111-1111-1111-111111111111",
  "brCode": "00020126580014br.gov.bcb.pix013600000000-0000-0000-0000-0000000000005204000053039865802BR5915Avenia API Ltda6009SAO PAULO62070503***6304XXXX",
  "createdAt": "2025-02-18T17:00:39.854943Z"
}

Field	Type	Description
`pixKey`	string	BRL deposit PIX key. Shared across the whole Business Account (same for every sub-account).
`brCode`	string	PIX copy-and-paste (QR) code, unique per account/sub-account. Use it to identify which sub-account a deposit belongs to.

tip

Prefer the brCode for deposit reconciliation: since the pixKey is shared, the per-sub-account brCode is what lets you attribute an incoming deposit to a specific sub-account.

Get Pix Info

The Pix Info endpoint provides information about the owner of a Pix key and their associated bank. It supports both Pix keys (e.g., CPF, email, phone number) and BR Codes.

Parameters

Field	Type	Description
pixKey	string	Here a BrCode or Pix Key that you would like to know more about
decodePixKey	bool	`true` runs the lookup in the Central Bank's Pix directory (DICT), which returns the key holder (`name`, `taxId`, `bankName`, `ispb`), for both Pix keys and BR Codes. Without it, only the data encoded in the BR Code itself (`amount`, `expiration`) is returned
subAccountId	string	Optional. The sub-account (end user) making the lookup. DICT lookups are rate-limited per user, so pass it to charge the lookup to that sub-account instead of the main account

warning

With decodePixKey, each lookup counts against the DICT rate limit of the account or sub-account making it. When the limit is reached, the endpoint returns HTTP 429. See DICT Lookup Limits.

Only the presence of decodePixKey is checked: decodePixKey=false also triggers a lookup. To skip it, leave the parameter out.

HTTP GET Request

https://api.sandbox.avenia.io:10952/v2/account/bank-accounts/brl/pix-info

cURL Example:

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/bank-accounts/brl/pix-info?pixKey=00000000000&decodePixKey=true" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response

{
  "name": "Herminia Kloth",
  "taxId": "***.456.789-**",
  "bankName": "Herminia Kloth",
  "ispb": "00000000",
  "amount": ""
}

Field	Type	Description
`name`	string	Account holder's name
`taxId`	string	Account holder's tax ID, as returned by the DICT: CNPJ in full, CPF partially masked (see below)
`bankName`	string	Human-readable name of the counterparty bank
`ispb`	string	The 8-digit ISPB code identifying the counterparty bank. Use it to cross-check against the blocked institutions list before creating a pay-out ticket
`amount`	string	Amount encoded in the BR Code, when present (empty for plain Pix keys)
`expiration`	string	Expiration of a dynamic BR Code (omitted otherwise)

Key holder data and CPF masking

The holder data returned with decodePixKey=true comes directly from the Central Bank of Brazil's Pix directory (DICT) and is returned as received:

CNPJ (companies) is returned in full.
CPF (individuals) is partially masked by the Central Bank, and the mask layout varies — for example 123.***.***-45 or ***.456.789-**. Your integration must accept both layouts.

No Avenia endpoint returns the full CPF behind a Pix key.

Binding a payment to a specific CPF/CNPJ

If you need the payment to go to a specific CPF or CNPJ, register the beneficiary bank account with full bank details (taxId, userName, bankCode, branchCode, accountNumber, accountType) instead of a Pix key. When you pay by Pix key, a taxId sent in the request is not used for validation.

In sandbox, the holder data is simulated.

DICT Lookup Limits

Pix key lookups (decodePixKey) query the Central Bank's DICT, which penalizes lookups for keys that are not registered. Each account and each sub-account has its own token bucket:

Rule	Value
Bucket size	60 tokens (a new bucket starts full)
Minimum balance to make a lookup	20 tokens
Key found	1 token
Key not found (`400 pixKey is invalid`)	20 tokens
Cached result	0 tokens, but the 20-token minimum still applies (found keys are cached for 7 days, not-found keys for 10 minutes)
Malformed key	free (rejected before the DICT lookup)
Refill	2 tokens per minute, plus 1 token per completed pay-out

Recommendations:

Pass subAccountId for the end user making the lookup. Without it, every lookup is charged to the main account's single bucket.
Validate the key format on your side, and don't repeat a key that returned 400. Show the error to the user instead.
Back off on 429. An immediate retry will fail again.
If you have a legitimate high-volume flow, contact us to raise the bucket size for specific users.

Check the Token Balance

https://api.sandbox.avenia.io:10952/v2/account/bank-accounts/brl/dict-tokens

Field	Type	Description
subAccountId	string	Optional. The sub-account whose bucket to read. Omit it to read the main account's bucket

cURL Example:

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/bank-accounts/brl/dict-tokens?subAccountId=00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response:

{
  "tokens": 41,
  "max": 60,
  "blocked": false
}

Field	Type	Description
`tokens`	integer	Current balance
`max`	integer	Bucket size
`blocked`	boolean	`true` when the balance is below the 20 tokens needed for a lookup

Conclusion

In this section, you have learned how to interact with the Bank Account - BRL within Avenia API:

✅ Retrieving Bank Account - BRL Information – Obtaining initialized bank account details.
✅ Getting Pix Info – Retrieving detailed information related to a Pix key or BR Code.
✅ DICT Lookup Limits – Charging lookups to the right sub-account and checking the token balance.

You now have the necessary understanding to handle BRL fiat rails effectively.

Introduction​

Bank Account - BRL Initialization​

Get Bank Account - BRL Information​

HTTP GET Request​

cURL Example:​

JSON Response​

Get a Sub-Account's Deposit PIX Key & BR Code​

Parameters​

HTTP GET Request​

cURL Example:​

JSON Response​

Get Pix Info​

Parameters​

HTTP GET Request​

JSON Response​

Key holder data and CPF masking​

DICT Lookup Limits​

Check the Token Balance​

Conclusion​

Introduction

Bank Account - BRL Initialization

Get Bank Account - BRL Information

HTTP GET Request

cURL Example:

JSON Response

Get a Sub-Account's Deposit PIX Key & BR Code

Parameters

HTTP GET Request

cURL Example:

JSON Response

Get Pix Info

Parameters

HTTP GET Request

JSON Response

Key holder data and CPF masking

DICT Lookup Limits

Check the Token Balance

Conclusion